doclets: Allow overloaded functions to not conflict #111
Conversation
|
|
I forgot to say it, but thanks for the patch! :-) I don't use TS myself, and nobody's maintaining sphinx-js's support at the moment, so I'm very keen to have your interest. |
|
Sure, I'm happy to add some tests for it. The error I was getting happens when building the docs. With the new behaviour, both overloads are listed in the docs, which is probably what you want (TypeDoc also lists both, but only one at a time, like this: https://typedoc.org/api/classes/application.html#generatedocs). Here's what the result looks like in sphinx-js: https://bistring.readthedocs.io/en/latest/JavaScript/Alignment.html#Alignment.originalBounds The tree that reports the conflicts is used to resolve links I believe. So when you write something like You're welcome for the patch! :) |
|
Tested it quickly, seems to work. This is definitely much better than throwing errors. Let's get some tests for this and merge it! |
tavianator
force-pushed
the
allow-overloads
branch
from
40b3e7b to
9e32dc7
Compare
|
@graup Added a simple test! |
|
@erikrose The code I changed doesn't distinguish between vanilla JS and TypeScript, so I'm pretty sure it won't. There's another issue as well: if you do something like |
There was a problem hiding this comment.
Hmm, so apparently we have more thinking to do here.
I'll leave it to you and weigh in once you come up with a design you feel good about. Feel free to let config flags be a part of it if necessary; that's fine with me as long as all nontrivial combinations of state have good test coverage.
I have regrets about the state of TS support in sphinx-js. The original contributor gave us a large piece of useful, well-tested code, but it hooked up TS by converting typedoc's output into the ill-specified, oft-changing JSON format jsdoc -X emits, because that's what sphinx-js operated on directly at the time (and still does). Had we talked during the design process, I'd have suggested we define a stable intermediate representation and write everything to that. But I was a teensy bit lazy in the 1.0 days, and now it's one of those temporary-begets-permanent situations. I'd still be happy to rewrite the JS parts to hook up to an IR—I think it would be borderline trivial—but I'm not prepared to tackle TS, as typedoc.py is full of branches and a mystery to me. Applicants welcome. :-)
|
@erikrose I'd be happy to contribute. Should we open a new issue to design an IR and coordinate working on a branch together? There are also some problems with some other ts features currently not supported by the jsdoc representation that we could fix then. |
|
I think an IR would be nice. Would enable us to have TS-specific things in the documentation as first-class citizens. To avoid needing to mess with typedoc.py at first, since we already have TypeDoc -> JSDoc, we could start with just doing TypeDoc -> JSDoc -> IR. Then later rewrite the conversion to just do TypeDoc -> IR, and compare the results on some corpus of existing TypeScript projects. I don't have a tremendous amount of time to contribute to this but I'm happy to review designs and implementations, and maybe do some of the TS side of it. |
|
Alright, I started doing some of the initial spec work toward an IR over at #120. Help is welcome! |
|
It doesn't crash anymore as of the great IR merge of #120, demonstrated by sphinx-js/tests/test_typedoc_analysis/test_typedoc_analysis.py Lines 336 to 344 in 705659c |
This uses a decorator to call post_convert after each call to `to_ir` so that it can't be forgotten. In order to allow subclasses to restrict the type of `to_ir`, we use a decorator (I originally tried a similar approach as with `type.render_name` but it doesn't work with the subclass type restrictions). Typing the decorator took a bit of trial and error, but the key thing is to say that the decorator doesn't change the type of the function.
Fixes #110.